### 功能描述

新建或保存定时任务；新建定时任务，定时任务状态默认为暂停，如有需要可调用update_cron_status接口开启。

### 请求参数

#### Body参数

| 字段              | 类型     | 必选 | 描述                                                                                |
|-----------------|--------|----|-----------------------------------------------------------------------------------|
| bk_scope_type   | string | 是  | 资源范围类型。可选值: biz - 业务，biz_set - 业务集                                                |
| bk_scope_id     | string | 是  | 资源范围ID, 与bk_scope_type对应, 表示业务ID或者业务集ID                                           |
| bk_biz_id       | long   | 是  | *已弃用*。业务ID。此字段已被弃用并由字段bk_scope_type+bk_scope_id替换                                 |
| job_plan_id     | long   | 是  | 要定时执行的作业的执行方案 ID                                                                  |
| id              | long   | 否  | 定时任务 ID，更新定时任务时，必须传这个值                                                            |
| name            | string | 否  | 定时作业名称，新建时必填，修改时选填                                                                |
| expression      | string | 否  | 定时任务 crontab 的定时规则，新建时必填，修改时选填，各字段含义为：分 时 日 月 周，如: 0/5 * * * * 表示每5分钟执行一次，注意：不支持? |
| execute_time    | long   | 否  | 定时任务单次执行的执行时间，Unix时间戳，新建定时任务时不可与expression同时为空                                    |
| global_var_list | array  | 否  | 全局变量信息，可使用 查询执行方案详情 接口查询方案可设置的变量信息                                                |

##### global_var

| 字段     | 类型     | 必选 | 描述                                     |
|--------|--------|----|----------------------------------------|
| id     | long   | 否  | 全局变量 id，唯一标识。如果 id 为空，那么使用 name 作为唯一标识 |
| name   | string | 否  | 全局变量 name                              |
| value  | string | 否  | 字符、密码、数组类型的全局变量的值                      |
| server | object | 否  | 主机类型全局变量的值                             |

##### server

| 字段                 | 类型    | 必选 | 描述                                                                                   |
|--------------------|-------|----|--------------------------------------------------------------------------------------|
| host_id_list       | array | 否  | 主机ID列表                                                                               |
| ip_list            | array | 否  | ***不推荐使用，建议使用host_id_list参数***;如果host_id_list与ip_list同时存在，将忽略ip_list参数。主机IP 列表，定义见ip |
| dynamic_group_list | array | 否  | 动态分组列表                                                                               |
| topo_node_list     | array | 否  | 动态 topo 节点列表                                                                         |

##### ip

| 字段          | 类型     | 必选 | 描述     |
|-------------|--------|----|--------|
| bk_cloud_id | int    | 是  | 管控区域ID |
| ip          | string | 是  | IP地址   |

##### topo_node

| 字段        | 类型     | 必选 | 描述                                                  |
|-----------|--------|----|-----------------------------------------------------|
| id        | long   | 是  | 动态topo节点ID，对应CMDB API 中的 bk_inst_id                 |
| node_type | string | 是  | 动态topo节点类型，对应CMDB API 中的 bk_obj_id,比如"module","set" |

### 请求参数示例

- POST

#### 1.创建定时任务

```json
{
    "bk_scope_type": "biz",
    "bk_scope_id": "1",
    "execute_time": 0,
    "expression": "0 0/5 * * *",
    "job_plan_id": 1023060,
    "name": "test API",
    "global_var_list": [
        {
            "name": "stringVar",
            "value": "value11112"
        },
        {
            "name": "nsVar",
            "value": "nsvalue11112"
        },
        {
            "name": "secretVar",
            "value": "secretvalue11112"
        },
        {
            "name": "dictVar",
            "value": "([\"var1\"]=1, [\"var2\"]=2)"
        },
        {
            "name": "indexArrVar",
            "value": "(2 3 4)"
        },
        {
            "name": "hostVar",
            "server": {
                "host_id_list": [
                    1,
                    2,
                    3
                ]
            }
        }
    ]
}
```

#### 2.更新定时任务

```json
{
    "id": 1000064,
    "bk_scope_type": "biz",
    "bk_scope_id": "1",
    "execute_time": 0,
    "expression": "0 0/5 * * *",
    "job_plan_id": 1023060,
    "name": "test API",
    "global_var_list": [
        {
            "name": "stringVar",
            "value": "value111333312"
        },
        {
            "name": "nsVar",
            "value": "nsvalue111333312"
        },
        {
            "name": "secretVar",
            "value": "secretvalue111333312"
        },
        {
            "name": "dictVar",
            "value": "([\"var1\"]=1, [\"var2\"]=2)"
        },
        {
            "name": "indexArrVar",
            "value": "(22 3 4)"
        },
        {
            "name": "hostVar",
            "server": {
                "host_id_list": [
                    2,
                    3,
                    4
                ]
            }
        }
    ]
}
```

### 返回结果示例

#### 1.创建定时任务

```json
{
    "code": 0,
    "result": true,
    "data": {
        "id": 1000067,
        "name": "test API",
        "status": 2,
        "creator": "admin",
        "bk_scope_type": "biz",
        "bk_scope_id": "1",
        "job_plan_id": 1023060,
        "expression": "0 0/5 * * *",
        "global_var_list": [
            {
                "id": 1001101,
                "name": "stringVar",
                "value": "value11112",
                "type": 1
            },
            {
                "id": 1001102,
                "name": "nsVar",
                "value": "nsvalue11112",
                "type": 2
            },
            {
                "id": 1001104,
                "name": "secretVar",
                "value": "secretvalue11112",
                "type": 4
            },
            {
                "id": 1001105,
                "name": "dictVar",
                "value": "([\"var1\"]=1, [\"var2\"]=2)",
                "type": 5
            },
            {
                "id": 1001106,
                "name": "indexArrVar",
                "value": "(2 3 4)",
                "type": 6
            },
            {
                "id": 1001103,
                "name": "hostVar",
                "type": 3,
                "server": {
                    "ip_list": [
                        {
                            "bk_host_id": 101,
                            "bk_cloud_id": 0,
                            "ip": "127.0.0.1"
                        }
                    ]
                }
            }
        ],
        "create_time": 1642045370,
        "last_modify_user": "admin",
        "last_modify_time": 1642045370
    },
    "job_request_id": "xxx"
}
```

#### 2.更新定时任务

```json
{
    "code": 0,
    "result": true,
    "data": {
        "id": 1000064,
        "name": "test API",
        "status": 2,
        "creator": "admin",
        "bk_scope_type": "biz",
        "bk_scope_id": "1",
        "job_plan_id": 1023060,
        "expression": "0 0/5 * * *",
        "global_var_list": [
            {
                "id": 1001101,
                "name": "stringVar",
                "value": "value111333312",
                "type": 1
            },
            {
                "id": 1001102,
                "name": "nsVar",
                "value": "nsvalue111333312",
                "type": 2
            },
            {
                "id": 1001104,
                "name": "secretVar",
                "value": "secretvalue111333312",
                "type": 4
            },
            {
                "id": 1001105,
                "name": "dictVar",
                "value": "([\"var1\"]=1, [\"var2\"]=2)",
                "type": 5
            },
            {
                "id": 1001106,
                "name": "indexArrVar",
                "value": "(22 3 4)",
                "type": 6
            },
            {
                "id": 1001103,
                "name": "hostVar",
                "type": 3,
                "server": {
                    "ip_list": [
                        {
                            "bk_host_id": 101,
                            "bk_cloud_id": 0,
                            "ip": "127.0.0.1"
                        }
                    ]
                }
            }
        ],
        "create_time": 1641990674,
        "last_modify_user": "admin",
        "last_modify_time": 1641995052
    },
    "job_request_id": "xxx"
}
```

### 返回结果参数说明

{% include '_generic_response.md.j2' %}

##### data

| 字段               | 类型     | 是否一定不为null | 描述                                      |
|------------------|--------|------------|-----------------------------------------|
| id               | long   | 是          | 定时任务 ID                                 |
| name             | string | 是          | 定时作业名称                                  |
| status           | int    | 是          | 定时任务状态                                  |
| bk_scope_type    | string | 是          | 资源范围类型。可选值: biz - 业务，biz_set - 业务集      |
| bk_scope_id      | string | 是          | 资源范围ID, 与bk_scope_type对应, 表示业务ID或者业务集ID |
| job_plan_id      | long   | 是          | 要定时执行的作业的执行方案 ID                        |
| creator          | string | 是          | 创建人                                     |
| create_time      | long   | 是          | 创建时间Unix时间戳（s）                          |
| last_modify_user | string | 是          | 最近一次修改人                                 |
| last_modify_time | long   | 是          | 最近一次修改时间Unix时间戳（s）                      |
| expression       | string | 否          | 定时任务 crontab 的定时规则，                     |
| execute_time     | long   | 否          | 定时任务单次执行的执行时间，Unix时间戳                   |
| global_var_list  | array  | 否          | 全局变量信息，定义见global_var                    |

##### global_var

| 字段     | 类型     | 是否一定不为null | 描述                                     |
|--------|--------|------------|----------------------------------------|
| id     | long   | 是          | 全局变量 id，唯一标识。如果 id 为空，那么使用 name 作为唯一标识 |
| name   | string | 是          | 全局变量名                                  |
| type   | int    | 是          | 全局变量类型                                 |
| value  | string | 否          | 字符、密码、数组类型的全局变量的值                      |
| server | object | 否          | 主机类型全局变量的值                             |

##### server

| 字段                 | 类型     | 是否一定不为null | 描述                 |
|--------------------|--------|------------|--------------------|
| variable           | string | 否          | 引用的变量名             |
| ip_list            | array  | 否          | 静态IP列表             |
| host_id_list       | array  | 否          | 静态主机ID列表，元素为Long类型 |
| dynamic_group_list | array  | 否          | 动态分组ID列表           |
| topo_node_list     | array  | 否          | 动态topo节点列表         |

##### ip

| 字段          | 类型     | 是否一定不为null | 描述     |
|-------------|--------|------------|--------|
| bk_cloud_id | int    | 是          | 管控区域ID |
| ip          | string | 是          | IP地址   |

##### dynamic_group

| 字段 | 类型     | 是否一定不为null | 描述      |
|----|--------|------------|---------|
| id | string | 是          | 动态分组 ID |

##### topo_node

| 字段        | 类型     | 是否一定不为null | 描述                                                  |
|-----------|--------|------------|-----------------------------------------------------|
| id        | long   | 是          | 动态topo节点ID，对应CMDB API 中的 bk_inst_id                 |
| node_type | string | 是          | 动态topo节点类型，对应CMDB API 中的 bk_obj_id,比如"module","set" |
